SemanticBSDD

Improving the GraphQL, JSON and RDF Representations of buildingSmart Data Dictionary

Vladimir Alexiev, Mihail Radkov, Nataliya Keberle

Objective

highlight the defects in the original GraphQL implementation of bSDD
overview the refactored solution proposed by Ontotext
overview the proposed improvements

bSDD GraphQL Schema: PlantUML

PlantUML is used with soml2puml convertor tool

Original GraphQL: Findings (1/3)

reference entities ReferenceDocument, Country, Unit, Language are disconnected from the rest of the schema
relation entities have only an incoming link but no outgoing link
many entities cannot be queried directly from the Root
no backward arrows to get from a lower-level entity back to its “parent” entity
a number of parallel arrows. GraphQL schema can use parameters to distinguish between the different uses

Original GraphQL: Findings (2/3)

At the high level of detail:

Property and ClassificationProperty are very similar, but there’s no inheritance/relation between them
PropertyValue and ClassificationPropertyValue are exactly the same, so can be reduced to one entity

Original GraphQL: Fragment

Original GraphQL: Findings (3/3)

Even more details:

mixture of singular/plural in property names

property/properties, relations, synonyms, countriesOfUse, relatedIfcPropertyNames, etc.

Refactored GraphQL: Improvements

all entities are queryable directly from the Root
link deduplication
each link is named the same as target entity
navigation between entities is bidirectional, e.g., Classification hierarchy can be navigated both up and down (parentClassification, childClassification)
a query can traverse a Relation entity to get data about the related entity:
- Classification.relation -> ClassificationRelation.related -> Classification
- Property.relation -> PropertyRelation.related -> Property
a single entity PropertyValue is used by both Property and ClassificationProperty
property names are in singular

Refactored GraphQL: Fragment

Graph i QL

Original
Refactored

Suggested Improvements

Presentation (1/3)

uniform identification for the search
equal data retrieved from different API
uniform URI design

Uniform Identification for the Search(1/3)

February 2023: IfcCableSegment has id: https://search.bsdd.buildingsmart.org/Classification/Index/58453

May 2023: IfcCableSegment has another id: https://search.bsdd.buildingsmart.org/Classification/Index/70992

Uniform Identification for the Search(2/3)

IfcCableSegment has also unique URI:

https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/class/IfcCableSegmentCABLESEGMENT

CableSegment entity as displayed at the bSDD web site

Uniform Identification for the Search(3/3)

Non-unique identification violates FAIR Findability principle

F1: (Meta)data are assigned a globally unique and persistent identifier

Equal Data Retrieved from Different API (1/2)

We have compared three representations returned by the bSDD server:

JSON from the GraphQL API
- https://test.bsdd.buildingsmart.org/graphiql/,
JSON from the REST (entity) API
- curl https://identifier.buildingsmart.org/uri/buildingsmart/ <domain>/class|prop/<name> and
RDF from the REST (entity) API
- curl -Haccept:text/turtle \\ https://identifier.buildingsmart.org/uri/buildingsmart/ <domain>/class|prop/<name>

Equal Data Retrieved from Different API (2/2)

We selected entities of each class that have the maximum number of filled fields, and compared the results returned by each API.

The differences are here:

Modelling

Data quality

Refactoring

Conclusions and Future Work

Here are further ideas for improvement:

improvement of bSDD ontology
implement more radical data model refactoring to convert “strings” (countries, reference documents, etc.) into “things”
link bSDD units of measure to QUDT ontology
perform deeper data quality analysis using SHACL shapes generation and validation provided by Ontotext Platform Semantic Objects
address and resolve more data quality issues, including
- seeking correlation between dimension vectors, units of measure and physical quantity,
- parsing out enumeration values from Property/ClassificationProperty descriptions and creation of corresponding PropertyValue lists
make more graph visualizations
obtain more interesting statistics using SPARQL

Acknowledgements

Funding: ACCORD project, Horizon Europe, grant #101056973

Data: buildingSMART Data Dictionary (bSI credits: Leon van Berlo, Artur Tomczak, Erik Baars)